Update CONTRIBUTING.md to enhance build instructions and component-sp… #201

charEtoile · 2025-11-07T10:23:39Z

Update CONTRIBUTING.md to enhance build instructions

…ecific build guidance

tonygermano

I've got a couple suggestions, but overall this looks great. Thank you for contributing!

CONTRIBUTING.md

tonygermano · 2025-11-07T15:27:38Z

CONTRIBUTING.md

+cd server
+ant -f mirth-build.xml dist
+```
+


Maybe add a section about starting the server after building? I see further down you indicated that server/setup is where the application is "installed" post-build. As of #119 there will be an oieserver bash script for linux/mac developers and oieserver.ps1 powershell script for windows developers placed in server/setup to launch the server with that will correctly pick up the vmoptions.

Hi, actually, I tried to start the client ... and the old java webstart was an issue. So i decided to upgrade the whole thing to a more recent JAVA, the 21. I updated the CONTRIBUTING.md to give running instructions. I added an oieclient script based on the oeiserver script.
https://github.com/charEtoile/engine/blob/update_sdk_to_21/CONTRIBUTING.md
I know that current tests fail, i am investigating.

As things currently stand, the project must compile with java 8, but the oieserver script requires the server is started with java 17 or higher. There are a couple work in progress PRs that will require java 17 for the build version, and 17 or higher for the runtime version.

OK.
I reverted back to Java 8 and added instructions for Java 17 runtime. All build tests pass.
I also added the oieclient script. Hope this is enough.

@charEtoile, I like the idea, but please consider pulling oieclient.sh into a separate PR. CONTRIBUTING.md certainly needs updates, but the resounding runtime pattern is to use a launcher to start the client. Changing that is a much larger change than documentation.

I will split the PR for the oeiclient.s script and its associated documentation. I focus mainly on dev, not necessarily on production, so maybe I should state somewhere that the script is provided as a convenience for developers rather than for use in production.

…ption -DdisableTests=true

…oo verbose)

…cy (make it run with 17.0.17.fx-zulu)

…utable

…n instructions; add images for client GUI

tonygermano

I haven't given a full review to the oieclient script yet. I'm not confident it is included in the correct place, but I can see how it could be useful during development, as there are other similar scripts already floating around.

I think rather than /server/base-includes that /tools/client-launcher or something similar may be a more appropriate location, but I'll wait for others to weigh in on that. I don't think it's a script that we want to ship with the installer, as it's very uncommon to launch the client from the server host in production, especially for a non-windows server. Typically, once the server is launched, a standard client launcher tool is used to connect. See https://docs.openintegrationengine.org/launchers/. Most of us use Ballista during development.

I also like the additional detail you've added about running the client since my last review, but I wonder if that is too much for the contributing guide and would be better placed on the documentation site linked above. I requested the information on starting the server since that is slightly different when running the build yourself vs installing the release, but the launching the client does not need to be different than in production. I'll let others provide feedback on this as well.

tonygermano · 2025-11-11T23:30:20Z

server/basedir-includes/oieserver


 # Launch Open Integration Engine (as this PID with exec)
 echo "Starting Open Integration Engine..."
-echo "$FINAL_JAVA_CMD ${JAVA_OPTS[*]}"


I don't think this line should be removed. Potentially it could require a verbose flag, but I think that change would belong in a different PR.

I'll see if I can add a verbose flag.

tonygermano · 2025-11-11T23:32:30Z

server/conf/custom.vmoptions

+
+# Use the Java version specified in .sdkmanrc (located in project root)
+# This ensures server runtime matches the build environment
+-java-cmd ${HOME}/.sdkman/candidates/java/17.0.17.fx-zulu/bin/java


This should not be added here. This file is included in the full release where the user is likely to not be using sdkman and does not have access to the project root.

mgaffigan

I love the intent and think you are going in a good direction. I think there are some changes needed, though:

Please split the oieclient and launcher changes to separate PR's to avoid delaying merge of the documentation changes. Current norm would be to use a launcher. Popular ones are MCAL, Ballista, and BridgeLink.
Focus on getting the contributor up and running in contributor.md, and reference the other published documentation without duplication.
- Define a single golden track that the contributor can follow to get a working build.
- Details and nuance on various topics would belong in the documentation website/repo, with perhaps a link in getting started.
- sdkman install should be from sdkman themselves.
- Build timeline and normal outputs might come from a reference to github actions build or to a blog article.

mgaffigan · 2025-11-12T03:24:39Z

CONTRIBUTING.md

-OIE specifies the working versions of Java and Ant in [.sdkmanrc](./.sdkmanrc). To take advantage of this, install [SDKMAN](https://sdkman.io/) and run `sdk env install`
-in the project's root directory.


Why are we moving away from sdk env install?

mgaffigan · 2025-11-12T03:25:46Z

CONTRIBUTING.md

+# Install SDKMAN (if not already installed)
+curl -s "https://get.sdkman.io" | bash
+source "$HOME/.sdkman/candidates/java/current/bin/java"


I would not repeat installation guidance given that it may change - perhaps a link to the relevant documentation.

mgaffigan · 2025-11-12T03:28:04Z

CONTRIBUTING.md

+
+**Set build-time Java:**
+```bash
+sdk use java 8.0.442.fx-zulu


This should not be required with sdk env install

mgaffigan · 2025-11-12T03:29:38Z

CONTRIBUTING.md

+ant -version   # Should show Ant 1.10.14
+```
+
+> **Important:** After building with Java 8, you'll need Java 17+ with JavaFX (`17.0.17.fx-zulu` or higher) to run the server and client. The runtime Java is specified in `conf/custom.vmoptions` for the server and `oieclient.vmoptions` for the client.


Server runtime java can also be configured by OIE_JAVA_HOME or by other means - not sure this should be in the getting started. Probably should be in the documentation for oieserver or similar.

mgaffigan · 2025-11-12T03:32:13Z

CONTRIBUTING.md

+> **Note:** This build takes approximately 2 minutes 20 seconds on a MacBook Pro M4 Pro.
+
+This will:
+- Build Donkey (message processing engine)
+- Build Server extensions
+- Build Client
+- Build Manager
+- Build CLI (Command Line Interface)
+- Run all tests
+- Create the complete setup in `server/setup/`
+
+**Fast Build (Skip Tests)**
+```bash
+cd server
+ant -f mirth-build.xml -DdisableSigning=true -DdisableTests=true
+```
+
+> **Note:** This build takes approximately 10-11 seconds on a MacBook Pro M4 Pro.
+
+Use this for faster builds during development when you don't need to run the full test suite.
+
+**Full Build (Signed - for releases)**
+```bash
+cd server
+ant -f mirth-build.xml
+```
+
+**Create Distribution Package**
+```bash
+cd server
+ant -f mirth-build.xml dist
+```


This is all good information, but probably does not need to be in the getting started. Perhaps in build system documentation. Not sure about including normative build speed - it's a figure that is unlikely to be updated over time, and will get out of date.

mgaffigan · 2025-11-12T03:34:23Z

CONTRIBUTING.md

+cd server
+ant -f mirth-build.xml dist
+```
+


@charEtoile, I like the idea, but please consider pulling oieclient.sh into a separate PR. CONTRIBUTING.md certainly needs updates, but the resounding runtime pattern is to use a launcher to start the client. Changing that is a much larger change than documentation.

mgaffigan · 2025-11-12T03:38:09Z

CONTRIBUTING.md

+
+Alternatively, install GNU tar on macOS:
+```bash
+brew install gnu-tar


+1 for brew install gnu-tar. More options = more problems. I don't think release procedures need to be in the quick start at all, let alone for Mac OS specifically.

mgaffigan · 2025-11-12T03:39:41Z

CONTRIBUTING.md

+
+#### Packaging
+
+After building, you can create a distribution tarball:


Note: this does not include installers. Installers are published using install4j, which requires a license to build.

mgaffigan · 2025-11-12T03:41:18Z

CONTRIBUTING.md

+gtar czf openintegrationengine.tar.gz -C server/ setup --transform 's|^setup|openintegrationengine/|'
+```
+
+#### Build Individual Components


I don't think this is needed for quick-start. Maybe in some IDE configuration documentation under. Quick start should be focused on getting started quickly, not efficiency. Deliver value to the contributor, and they will keep reading on how to become efficient.

Update CONTRIBUTING.md to enhance build instructions and component-sp…

163d237

…ecific build guidance

tonygermano requested changes Nov 7, 2025

View reviewed changes

charEtoile added 5 commits November 7, 2025 17:09

Update CONTRIBUTING.md to clarify build commands and add fast build o…

618671f

…ption -DdisableTests=true

Remove debug output for final Java command in oieserver script (was t…

8db8d0c

…oo verbose)

Add custom Java command to server vmoptions for environment consisten…

436f9fd

…cy (make it run with 17.0.17.fx-zulu)

Add OIE client launcher script and VM options file; make scripts exec…

05d54aa

…utable

Update CONTRIBUTING.md with Java version requirements and installatio…

7125d9e

…n instructions; add images for client GUI

tonygermano requested changes Nov 12, 2025

View reviewed changes

tonygermano requested review from a team, gibson9583, jonbartels, kayyagari, kpalang, pacmano1, ssrowe and tonygermano and removed request for a team November 12, 2025 00:11

mgaffigan requested changes Nov 12, 2025

View reviewed changes

		OIE specifies the working versions of Java and Ant in [.sdkmanrc](./.sdkmanrc). To take advantage of this, install [SDKMAN](https://sdkman.io/) and run `sdk env install`
		in the project's root directory.


		#### Packaging

		After building, you can create a distribution tarball:

Update CONTRIBUTING.md to enhance build instructions and component-sp… #201

Are you sure you want to change the base?

Update CONTRIBUTING.md to enhance build instructions and component-sp… #201

Conversation

charEtoile commented Nov 7, 2025

Uh oh!

tonygermano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tonygermano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mgaffigan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants